Skip to content

feat(lifecycle): detached handoff supervisor with OS-owned callback - #14

Draft
nullStack65 wants to merge 1 commit into
mainfrom
env1/lifecycle-handoff-20261001
Draft

nullStack65 wants to merge 1 commit into
mainfrom
env1/lifecycle-handoff-20261001

Conversation

@nullStack65

Copy link
Copy Markdown
Owner

Detached T3 lifecycle handoff (supervisor + callback)

An agent running inside T3 cannot upgrade T3: the lifecycle action kills the agent
before it can report back. This adds a detached handoff that moves the action to
an OS-owned supervisor whose lifetime is independent of T3.

Draft. Non-overlapping with the Windows SCM lifecycle work on #10 (no shared
files: prepared #10 changes and this branch touch disjoint paths). Related
lifecycle hub: #10; environment coordinator: nullStack65/closura-agent-config#237.

What is here

  • Envelope (lib/envelope.mjs): owner-private, credentials refused at write
    time, describes originating thread/project/machine, command, wait target,
    relaunch, readiness, identity and callback.
  • macOS: transient per-handoff LaunchAgent (RunAtLoad, KeepAlive=false,
    Background). Its direct parent is launchd (pid 1), so T3/Electron job-object
    teardown cannot reach it. It removes its own plist and bootctl bootouts itself.
  • Windows: transient current-user Scheduled Task (InteractiveToken,
    LeastPrivilege, one-shot). Implemented; not executed on a Windows host.
  • State machine (lib/run.mjs): PREPARED → DETACHED → WAITING_FOR_EXIT → APPLYING → RELAUNCHING → WAITING_FOR_T3 → CALLBACK_PENDING → COMPLETE/FAILED,
    single-run claim, terminal-result idempotency that refuses to re-run the
    destructive command, bounded timeouts, and a hard rule that a still-alive
    waited-for pid fails the handoff rather than being force-killed.
  • Independence proof (lib/process.mjs): parent chain walk asserting
    directParent === 1 and no initiator ancestor — required before the initiator
    may quit T3.
  • Callback contract: terminal result envelope + gh durable receipt
    (or generic HTTP POST). No state.sqlite writes, no fabricated orchestration
    events, no copied auth tokens.
  • Docs: docs/internals/lifecycle-handoff.md (Mac, Windows, callback
    contract, security model, recovery, agent invocation). Operator README under
    scripts/lifecycle-handoff/.

Evidence on this head

  • Unit: node --test test/envelope.test.mjs test/run.test.mjs → 11 passed / 0 failed.
  • Real macOS fixture: node --test test/fixture.integration.test.mjs → 1 passed.
    Real LaunchAgent; fake parent prepares a handoff and exits; the detached
    supervisor survives (independence proof: pid directParent=1, ancestry [1],
    independent=true), runs the harmless command, relaunches a fake service,
    delivers the callback exactly once (state=COMPLETE), unregisters its own job,
    and refuses to re-run on idempotent replay.
  • Full suite: 12 passed / 0 failed.

Callback status

T3 exposes no supported CLI/REST callback today; the only mutation transport
is authenticated /ws orchestration.dispatchCommand. This PR therefore ships the
result-envelope + GitHub-receipt fallback behind a stable callback.kind, so a
future supported endpoint slots in without touching lifecycle logic.

NOT DONE (explicit)

  • Windows execution on a Windows host (source + docs only).
  • Real-T3 restart smoke is not run from an active initiating session (it would
    terminate that session); the mechanism is proven by the fixture. Run it from an
    idle T3 with a bounded, non-mutating command.
  • No wiring into bin.ts; invocation is documented in the README.
  • No packaging/CI/merge. Not independently reviewed.

An agent running inside T3 cannot upgrade T3: the lifecycle action kills the
agent before it can report back. This adds a detached handoff that moves the
action to an OS-owned supervisor whose lifetime is independent of T3.

- handwritten envelope (owner-private, credentials refused) describing the
  originating thread, command, wait target, relaunch, readiness and callback;
- macOS: transient per-handoff LaunchAgent; Windows: transient current-user
  Scheduled Task (InteractiveToken, LeastPrivilege, one-shot);
- explicit state machine PREPARED..COMPLETE/FAILED, single-run claim, and
  terminal-result idempotency that refuses to re-run the destructive command;
- independence proof (direct parent pid 1, no initiator ancestor) required
  before the initiator may stop T3;
- callback contract: local result envelope + GitHub receipt; no state.sqlite
  writes, no fabricated orchestration events, no copied credentials.

Zero-dependency ESM under scripts/lifecycle-handoff with unit tests and a real
launchd fixture (fake parent exits, supervisor survives, runs a harmless
command, relaunches a fake service, calls back once, unregisters itself).

Non-overlapping with the Windows SCM lifecycle work on PR #10.
@github-actions github-actions Bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Oct 1, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant